/*
 * Copyright 2008 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package blms.services;

import java.io.File;
import java.io.Serializable;
import java.util.List;

import blms.domain.User;
import blms.exception.RestrictionException;
import blms.exception.UserDoesNotExistException;
import blms.exception.ValidationException;

/**
 * This service handles creation, update and deletion of users. It is a service
 * interface to CRUD operations.
 * 
 * @author Jonhnny Weslley
 * @author Thiago Emmanuel Pereira da Cunha Silva, thiago.manel@gmail.com
 * @version 1.00, 21/04/2008
 * @since 1.0
 */
public interface UserService {

	/**
	 * Creates and adds a new user for the system.
	 * 
	 * @param firstName
	 *            The first name of the user.
	 * @param lastName
	 *            The last name of the user.
	 * @param homePhone
	 *            The home phone of the user.
	 * @param workPhone
	 *            The work phone of the user.
	 * @param cellPhone
	 *            The cell phone of the user.
	 * @param email
	 *            The email of the user. This attribute will uniquely identify
	 *            the user.
	 * @param picture
	 *            A picture of the user.
	 * 
	 * @return The ID of the user created.
	 * @throws ValidationException
	 *             The creation parameters should follow the <code>User</code>
	 *             value validation rules
	 * @throws RestrictionException
	 * 			Could not create a user, if already exists another user with the
	 * 			same email
	 */
	User createUser(String firstName, String lastName, String homePhone,
			String workPhone, String cellPhone, String email, File picture)
			throws ValidationException, RestrictionException;

	/**
	 * Looks up an user.
	 * 
	 * @param id
	 * @return.
	 * @throws UserDoesNotExistException
	 *             if there is not an user with the id.
	 */
	User getUser(Serializable id) throws UserDoesNotExistException;

	/**
	 * Returns <tt>true</tt> if there is an user with the specified id.
	 * 
	 * @param id
	 * @return <tt>true</tt> if there is an user with the specified id.
	 */
	boolean contains(Serializable id);

	/**
	 * Returns <tt>true</tt> if there is an user with the specified email.
	 * 
	 * @param email
	 * @return <tt>true</tt> if there is an user with the specified email.
	 */
	boolean containsEmail(String email);

	/**
	 * Looks up the user with the specified email.
	 * 
	 * @param email
	 *            The email of the user to be found
	 * @return The user with the specified email
	 * @throws UserDoesNotExistException
	 *             if there is not an user with email.
	 */
	User findUserByEmail(String email) throws UserDoesNotExistException;

	/**
	 * Looks up to users thats the last name matches with lastNamePattern.
	 * 
	 * @param lastNamePattern
	 *            The last name pattern of the users to be found
	 * @return User's ids thats the last name matches with lastNamePattern.
	 * @throws UserDoesNotExistException
	 *             if there is not an user with lastNamePattern.
	 */
	List<String> findUserByLastName(String lastNamePattern)
			throws UserDoesNotExistException;

	/**
	 * @param user
	 * @throws ValidationException
	 */
	void updateUser(User user) throws ValidationException;

	/**
	 * Removes the specified user from the system.
	 * 
	 * @param id
	 *            The id of the user to be removed.
	 * @throws UserDoesNotExistException
	 *             if there is not an user with the id parameter.
	 * @throws RestrictionException 
	 *             Could not delete a league operator user.
	 */
	void deleteUser(Serializable id) throws UserDoesNotExistException, RestrictionException;

	/**
	 * Cleans the internal state, removing all the users.
	 */
	void removeAllUsers();

}
